{ "openapi": "3.1.0", "info": { "contact": { "email": "support@hive.app", "name": "Hive Support", "url": "https://developers.hive.app" }, "description": "The Merchant API lets merchants integrate their own systems, such as a store or an ERP for which Hive has no native integration, with Hive.\n\nYou can create SKUs and orders, and read back the fulfillment and delivery status of orders. You can also work with other parts of Hive's warehouse management: restocking shipments, returns and warehouses.\n\nThe API does not give access to all the data and features of the Hive app. An access token belongs to one sales channel (shop): SKUs, orders and shipments are scoped to that shop, while restocking shipments, returns and warehouses are scoped to the merchant that owns it. If your platform is listed in [Hive's integration list](https://www.hive.app/product/integrations), you do not need this API.\n\n## Versioning\nThis is version 1 of the Merchant API. It stays available for existing integrations but is frozen: new features are only added to v2, and new integrations should use v2. The same access tokens work for both versions.\n\n## Access tokens\nEvery request must be authenticated with an API access token, sent as a bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer your_api_token\n```\n\nAsk your account manager for a token. The production domain is `https://app.hive.app`, the staging domain is `https://staging.app.hive.app`.\n\nA missing or unknown token is answered with `401 Unauthorized`. A token that has expired, or whose sales channel is no longer active, is answered with `403 Forbidden`.\n\n## Requests\nRequest bodies are JSON. Every request to v1 is read as JSON, whatever its `Content-Type` header says, but sending `Content-Type: application/json` is recommended. A body that is not valid JSON is answered with `400 Bad Request`. Numeric properties of a request body also accept numeric strings, such as `\"42000\"`, and a number sent for a string property is stored as its text.\n\nEndpoints that take a whole resource (creating or updating an order, creating a SKU, and each item of a SKU bulk upsert) reject properties they do not know with `422 Unprocessable Entity`; the properties they accept but ignore are listed as such. The other endpoints ignore unknown properties.\n\n## Errors\nA failed request answers with a `4xx` status code and a JSON body whose `errors` property is an array of human-readable messages:\n\n```json\n{\n \"success\": false,\n \"errors\": [\"Name can't be blank\", \"Merchant sku can't be blank\"]\n}\n```\n\nThe common cases are `400` for a malformed request, `401` and `403` for authentication problems, `404` when the requested record does not exist or does not belong to you, `409` when a record with the same data already exists, `422` when the data is invalid, and `429` when the rate limit is exceeded.\n\n## Pagination\nList endpoints, except `GET /warehouses`, are paginated. The response is an object with the records in `data` and the page information in `pagination`:\n\n```json\n{\n \"data\": [],\n \"pagination\": {\n \"current_page\": 1,\n \"item_count\": 2,\n \"page_count\": 1,\n \"items_per_page\": 20\n }\n}\n```\n\nPass `page` to choose a page (it starts at 1, the default) and `limit` to choose the page size (default 20). A `limit` above 100 is treated as 100. A `page` past the last one returns an empty `data` array. `pagination.page_count` tells how many pages there are.\n\nMost list endpoints also accept `created_at[gt]`, `created_at[gte]`, `created_at[lt]` and `created_at[lte]` to filter by creation time, as ISO 8601 date-times.\n\n## Rate Limiting\nRequests are rate limited per sales channel, by default to 100 requests per calendar minute (UTC). If you have a valid use case for a higher limit, contact your account manager. Real-time updates are available through webhooks, so frequent polling should not be necessary.\n\nResponses carry two headers with the current usage:\n\n```\nX-Rate-Limit-Used: 42\nX-Rate-Limit-Max: 100\n```\n\nRequests over the limit are answered with `429 Too Many Requests` and a `Retry-After` header giving the number of seconds until the next minute starts, for example `Retry-After: 3.2`.\n\n## Webhooks\nWebhooks notify you of events as they happen, for example when the delivery status of a shipment changes. Hive sends an HTTP `POST` request with a JSON body to the URL you registered for the event. To set up webhooks, give your account manager the URL for each event you want to receive.\n\nv1 webhooks are separate from v2 webhooks: a URL registered for v1 receives the v1 events below, whose body is the bare v1 resource (the same object the v1 endpoints return), with no envelope around it. See the `webhooks` section below for each event and its payload.\n\n- `delivery_status_updated`: the carrier delivery status of a shipment changed. The payload is a Shipment.\n- `shipment_status_updated`: the fulfillment status of a shipment changed. The payload is a Shipment.\n- `restocking_shipment_status_updated`: the status of a restocking shipment changed. The payload is a RestockingShipment.\n- `return_status_updated`: the status of a return changed. The payload is a Return.\n\nAnswer with a `2xx` status to acknowledge a webhook; Hive does not follow redirects, and any status below `400` counts as received. Hive waits 5 seconds for the answer. A timeout, a connection failure or a `5xx` status is retried with growing intervals, up to 12 attempts over about 11 to 13 hours; `429` answers are retried the same way, counted separately. Any other `4xx` status is treated as a rejection of the payload and is not retried.\n\n### Webhook Security\nHive signs each webhook request with an `x-hive-signature` header whenever the sales channel has a valid API token (without one, the header is left out): the hex-encoded HMAC-SHA256 digest of the request body, keyed with your API token. If the sales channel has several valid tokens, the oldest one is the key. Ignore requests without this header or whose signature does not match.\n\n```ruby\ndef request_valid?(req) # req is a Rack::Request\n return false if !req.post?\n request_sig = req.get_header(\"HTTP_X_HIVE_SIGNATURE\")\n expected_sig = OpenSSL::HMAC.hexdigest(\"sha256\", ENV[\"API_TOKEN\"], req.body.read)\n Rack::Utils.secure_compare(request_sig.to_s, expected_sig)\nend\n```\n\n### Webhook Reliability\nWebhook handlers should be idempotent. Hive does not guarantee the order of the calls, and a retried call carries the same payload again. Each request has an `x-hive-event-id` header, which stays the same across the retries of one call. Compare the timestamps in the payload with the last update you stored, and ignore a payload older than what you have.\n", "title": "Merchant API v1", "version": "1.0.0" }, "servers": [ { "description": "Production API", "url": "https://app.hive.app/merchant_api/v1" }, { "description": "Staging API", "url": "https://staging.app.hive.app/merchant_api/v1" } ], "security": [ { "BearerAuth": [] } ], "webhooks": { "delivery_status_updated": { "summary": "Delivery Status Updated", "description": "Sent when the carrier delivery status of a shipment changes.", "post": { "summary": "Shipment delivery status updated", "description": "Sent when the carrier reports a new delivery status for a shipment. The payload is the shipment as `GET /shipments` returns it, with the new `delivery_status`.\n\nNot sent for shipments without a tracking code.\n", "operationId": "deliveryStatusUpdatedWebhook", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "responses": { "200": { "description": "Any 2xx status acknowledges the webhook." } } } }, "shipment_status_updated": { "summary": "Shipment Status Updated", "description": "Sent when the fulfillment status of a shipment changes.", "post": { "summary": "Shipment status updated", "description": "Sent when a shipment moves to another fulfillment status. The payload is the shipment as `GET /shipments` returns it, with the new `status`. Unlike `GET /shipments`, which only lists shipped shipments, this event is sent for every status.\n", "operationId": "shipmentStatusUpdatedWebhook", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "responses": { "200": { "description": "Any 2xx status acknowledges the webhook." } } } }, "restocking_shipment_status_updated": { "summary": "Restocking Shipment Status Updated", "description": "Sent when the status of a restocking shipment changes.", "post": { "summary": "Restocking shipment status updated", "description": "Sent when a restocking shipment moves to another status. The payload is the restocking shipment as `GET /restocking_shipments/{id}` returns it. Restocking shipments belong to the merchant, so the event is sent to every sales channel of the merchant that registered a URL for it.\n", "operationId": "restockingShipmentStatusUpdatedWebhook", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestockingShipment" } } } }, "responses": { "200": { "description": "Any 2xx status acknowledges the webhook." } } } }, "return_status_updated": { "summary": "Return Status Updated", "description": "Sent when the status of a return changes.", "post": { "summary": "Return status updated", "description": "Sent when a return moves to another status. The payload is the return as `GET /returns/{id}` returns it. The event goes to the sales channel of the returned order.\n", "operationId": "returnStatusUpdatedWebhook", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookEventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Return" } } } }, "responses": { "200": { "description": "Any 2xx status acknowledges the webhook." } } } } }, "tags": [ { "description": "Operations related to orders", "name": "Orders" }, { "description": "Operations related to restocking shipments, the inbound deliveries of stock to a Hive warehouse", "name": "RestockingShipments" }, { "description": "Operations related to returns", "name": "Returns" }, { "description": "Operations related to Stock Keeping Units (SKUs)", "name": "SKUs" }, { "description": "Operations related to outbound shipments", "name": "Shipments" }, { "description": "Operations related to warehouses", "name": "Warehouses" }, { "description": "Webhook event notifications", "name": "Webhooks" } ], "paths": { "/orders": { "get": { "description": "Returns the orders of the sales channel, newest first. Orders created manually in the Hive app are not included.\n\nThe `created_at` filters apply to the time Hive received the order, which can differ from the order's own `created_at`.\n", "operationId": "listOrders", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/CreatedAtGt" }, { "$ref": "#/components/parameters/CreatedAtGte" }, { "$ref": "#/components/parameters/CreatedAtLt" }, { "$ref": "#/components/parameters/CreatedAtLte" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "The orders on this page.", "items": { "$ref": "#/components/schemas/Order" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Where this page sits in the whole result." } }, "required": [ "data", "pagination" ], "type": "object" } } }, "description": "A page of orders" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "List orders", "tags": [ "Orders" ] }, "post": { "description": "Creates an order. Hive fulfills it unless its destination country is blocked for the sales channel.\n\n`merchant_order_id` must be unique within the sales channel. Sending one that already exists is answered with `409 Conflict`, and the `metadata.id` of the error is the Hive ID of the existing order.\n", "operationId": "createOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The created order" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Create an order", "tags": [ "Orders" ] } }, "/orders/{id}": { "parameters": [ { "$ref": "#/components/parameters/OrderId" } ], "get": { "description": "Returns one order of the sales channel.", "operationId": "getOrder", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The order" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Get an order", "tags": [ "Orders" ] }, "patch": { "description": "Updates an order. Properties you leave out keep their current value, and so do most properties sent as `null` (see the request body); `shipping_address` is merged property by property.\n\nWhen you send `items`, it is the order's complete item list: items are matched to the existing ones by `merchant_item_id`, and existing items missing from it are cancelled. Cancelled items are still listed in the response's `items`.\n\n`merchant_order_id` identifies the order and must not change: an update with a different value does not rename this order, it creates or updates the order with that `merchant_order_id` instead and responds with it.\n", "operationId": "updateOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdate" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The updated order" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Update an order", "tags": [ "Orders" ] }, "put": { "description": "The same as `PATCH /orders/{id}`, which is the documented method. `PUT` is accepted too and behaves identically, including merging the properties you leave out.", "operationId": "updateOrderWithPut", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdate" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The updated order" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Update an order (PUT)", "tags": [ "Orders" ] } }, "/orders/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/OrderId" } ], "put": { "description": "Cancels an order that Hive has not started fulfilling yet. The order's `status` becomes `unfulfillable`.\n\nAnswers with `422 Unprocessable Entity` when fulfillment has already started, or when Hive has not processed the order yet.\n", "operationId": "cancelOrder", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "The cancelled order" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Cancel an order", "tags": [ "Orders" ] } }, "/restocking_shipments": { "get": { "description": "Returns the merchant's restocking shipments, newest first. Only restocking shipments with at least one item of a SKU the merchant's sales channels know are included.\n", "operationId": "listRestockingShipments", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "The restocking shipments on this page.", "items": { "$ref": "#/components/schemas/RestockingShipment" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Where this page sits in the whole result." } }, "required": [ "data", "pagination" ], "type": "object" } } }, "description": "A page of restocking shipments" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "List restocking shipments", "tags": [ "RestockingShipments" ] }, "post": { "description": "Announces a restocking shipment to a Hive warehouse. The new restocking shipment has the status `shipped`.\n", "operationId": "createRestockingShipment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestockingShipmentCreate" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestockingShipment" } } }, "description": "The created restocking shipment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Create a restocking shipment", "tags": [ "RestockingShipments" ] } }, "/restocking_shipments/{id}": { "parameters": [ { "$ref": "#/components/parameters/RestockingShipmentId" } ], "get": { "description": "Returns one of the merchant's restocking shipments.", "operationId": "getRestockingShipment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestockingShipment" } } }, "description": "The restocking shipment" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Get a restocking shipment", "tags": [ "RestockingShipments" ] }, "put": { "description": "Updates a restocking shipment while its status is `created` or `shipped`; in any other status the update is answered with `422 Unprocessable Entity`.\n\nThe top-level properties you leave out keep their value. `restocking_shipment_items` always replaces the whole item list: leaving it out removes every item.\n\nThe response lists the items without their `inventory_batches`, which are always empty here.\n", "operationId": "updateRestockingShipment", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestockingShipmentUpdate" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestockingShipment" } } }, "description": "The updated restocking shipment" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Update a restocking shipment", "tags": [ "RestockingShipments" ] } }, "/restocking_shipments/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/RestockingShipmentId" } ], "put": { "description": "Cancels a restocking shipment whose status is `created`, `shipped`, `delivered`, `arrived` or `on_hold`. In any other status the cancellation is answered with `422 Unprocessable Entity`.\n", "operationId": "cancelRestockingShipment", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "An empty object.", "type": "object" } } }, "description": "The restocking shipment was cancelled" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Cancel a restocking shipment", "tags": [ "RestockingShipments" ] } }, "/returns": { "get": { "description": "Returns the returns of the orders of all the merchant's sales channels, newest first. Only returns whose order is also a Merchant API order (one `/orders` can return) are listed; returns of orders that reached Hive any other way are not.\n", "operationId": "listReturns", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/CreatedAtGt" }, { "$ref": "#/components/parameters/CreatedAtGte" }, { "$ref": "#/components/parameters/CreatedAtLt" }, { "$ref": "#/components/parameters/CreatedAtLte" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "The returns on this page.", "items": { "$ref": "#/components/schemas/Return" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Where this page sits in the whole result." } }, "required": [ "data", "pagination" ], "type": "object" } } }, "description": "A page of returns" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "List returns", "tags": [ "Returns" ] } }, "/returns/{id}": { "parameters": [ { "$ref": "#/components/parameters/ReturnId" } ], "get": { "description": "Returns one of the merchant's returns.", "operationId": "getReturn", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Return" } } }, "description": "The return" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Get a return", "tags": [ "Returns" ] } }, "/shipments": { "get": { "description": "Returns the shipped shipments of the sales channel's orders, newest first. Shipments that have not been shipped yet are not listed; their status changes are available through the `shipment_status_updated` webhook.\n\nFilter by order with `order_id` or `merchant_order_id`. When both are given, `order_id` is used. An order that does not exist in the sales channel is answered with `404 Not Found`.\n", "operationId": "listShipments", "parameters": [ { "description": "The Hive ID of the order whose shipments to return.", "in": "query", "name": "order_id", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The merchant's order ID (`merchant_order_id`) of the order whose shipments to return.", "in": "query", "name": "merchant_order_id", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/CreatedAtGt" }, { "$ref": "#/components/parameters/CreatedAtGte" }, { "$ref": "#/components/parameters/CreatedAtLt" }, { "$ref": "#/components/parameters/CreatedAtLte" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "The shipments on this page.", "items": { "$ref": "#/components/schemas/Shipment" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Where this page sits in the whole result." } }, "required": [ "data", "pagination" ], "type": "object" } } }, "description": "A page of shipments" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "List shipments", "tags": [ "Shipments" ] } }, "/skus": { "get": { "description": "Returns the SKUs of the sales channel in every status, including deleted ones, newest first.\n", "operationId": "listSkus", "parameters": [ { "description": "Only return the SKUs with these merchant SKU IDs (`merchant_sku_id`). Repeat the parameter for each value.", "explode": true, "in": "query", "name": "merchant_sku_ids[]", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/CreatedAtGt" }, { "$ref": "#/components/parameters/CreatedAtGte" }, { "$ref": "#/components/parameters/CreatedAtLt" }, { "$ref": "#/components/parameters/CreatedAtLte" } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "The SKUs on this page.", "items": { "$ref": "#/components/schemas/Sku" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Where this page sits in the whole result." } }, "required": [ "data", "pagination" ], "type": "object" } } }, "description": "A page of SKUs" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "List SKUs", "tags": [ "SKUs" ] }, "post": { "description": "Creates a SKU, or updates the sales channel's SKU with the same `merchant_sku_id` if there is one; either way the SKU is active afterwards and the response is `201 Created`.\n\nWhen an existing SKU is updated, the properties you leave out are cleared, except `batch_tracking_enabled`, which keeps its value.\n", "operationId": "createSku", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuCreate" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sku" } } }, "description": "The created or updated SKU" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Create a SKU", "tags": [ "SKUs" ] } }, "/skus/bulk_upsert": { "post": { "description": "Creates or updates up to 100 SKUs in one request. Each item of `skus` has the same properties as the body of `POST /skus` and is matched to an existing SKU by `merchant_sku_id`; when two items share a `merchant_sku_id`, only the first is used.\n\nFor an existing SKU, the properties you leave out are cleared, except `batch_tracking_enabled`, which keeps its value unless you send it.\n\nThe items are validated before anything is saved. If one is invalid, the response is `422 Unprocessable Entity` with that item's errors, and no SKU is changed.\n", "operationId": "bulkUpsertSkus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuBulkUpsert" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "The created and updated SKUs, newest first.", "items": { "$ref": "#/components/schemas/Sku" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created and updated SKUs" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_skus": { "summary": "skus is missing, empty or not an array", "value": { "success": false, "errors": [ "Pass array with at least one item for upsert by 'skus' key" ] } }, "too_many_skus": { "summary": "More than 100 items", "value": { "success": false, "errors": [ "Disallowed to pass more than 100 items at once" ] } }, "malformed": { "summary": "The body is not valid JSON", "value": { "success": false, "errors": [ "bad request" ] } } } } }, "description": "The body is not valid JSON, `skus` is missing or empty, or it has more than 100 items" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Create or update SKUs in bulk", "tags": [ "SKUs" ] } }, "/skus/{id}": { "parameters": [ { "$ref": "#/components/parameters/SkuId" } ], "patch": { "description": "Updates a SKU of the sales channel. The properties you leave out keep their value, and a `null` `batch_tracking_enabled` is ignored. The SKU is active afterwards, even if it was deleted.\n", "operationId": "updateSku", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuUpdate" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sku" } } }, "description": "The updated SKU" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Update a SKU", "tags": [ "SKUs" ] }, "put": { "description": "The same as `PATCH /skus/{id}`, which is the documented method. `PUT` is accepted too and behaves identically, including keeping the properties you leave out.", "operationId": "updateSkuWithPut", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuUpdate" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sku" } } }, "description": "The updated SKU" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Update a SKU (PUT)", "tags": [ "SKUs" ] }, "delete": { "description": "Marks an active SKU as deleted. The next create, update or bulk upsert of the SKU makes it active again. A SKU that is not active (already deleted, archived or a draft) is answered with `404 Not Found`.\n", "operationId": "deleteSku", "responses": { "204": { "description": "The SKU was deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "Delete a SKU", "tags": [ "SKUs" ] } }, "/warehouses": { "get": { "description": "Returns all the merchant's warehouses. This list is not paginated.", "operationId": "listWarehouses", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "The merchant's warehouses.", "items": { "$ref": "#/components/schemas/Warehouse" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The merchant's warehouses" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "summary": "List warehouses", "tags": [ "Warehouses" ] } } }, "components": { "securitySchemes": { "BearerAuth": { "description": "The API access token, sent as `Authorization: Bearer `.", "scheme": "bearer", "type": "http" } }, "headers": { "RateLimitMax": { "description": "The maximum number of requests allowed per minute.", "schema": { "type": "integer" } }, "RateLimitUsed": { "description": "The number of requests made in the current minute, this one included.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds until the next minute starts, with one decimal, for example `3.2`.", "schema": { "type": "number" } } }, "parameters": { "CreatedAtGt": { "description": "Only return records created after this time (ISO 8601).", "in": "query", "name": "created_at[gt]", "required": false, "schema": { "type": "string" } }, "CreatedAtGte": { "description": "Only return records created at or after this time (ISO 8601).", "in": "query", "name": "created_at[gte]", "required": false, "schema": { "type": "string" } }, "CreatedAtLt": { "description": "Only return records created before this time (ISO 8601).", "in": "query", "name": "created_at[lt]", "required": false, "schema": { "type": "string" } }, "CreatedAtLte": { "description": "Only return records created at or before this time (ISO 8601).", "in": "query", "name": "created_at[lte]", "required": false, "schema": { "type": "string" } }, "Limit": { "description": "The number of records per page. A value above 100 is treated as 100.", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "minimum": 1, "type": "integer" } }, "OrderId": { "description": "The Hive ID of the order.", "in": "path", "name": "id", "required": true, "schema": { "format": "int64", "type": "integer" } }, "Page": { "description": "The page to return, starting at 1. A page past the last one returns no records.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "integer" } }, "RestockingShipmentId": { "description": "The Hive ID of the restocking shipment.", "in": "path", "name": "id", "required": true, "schema": { "format": "int64", "type": "integer" } }, "ReturnId": { "description": "The Hive ID of the return.", "in": "path", "name": "id", "required": true, "schema": { "format": "int64", "type": "integer" } }, "SkuId": { "description": "The Hive ID of the SKU.", "in": "path", "name": "id", "required": true, "schema": { "format": "int64", "type": "integer" } }, "WebhookEventId": { "description": "Identifies the webhook call. Retries of the same call carry the same value.", "in": "header", "name": "x-hive-event-id", "required": true, "schema": { "type": "string", "examples": [ "8a6f3c2e-5b1d-4c7e-9f0a-2d3b4c5e6f70" ] } }, "WebhookSignature": { "description": "Hex-encoded HMAC-SHA256 digest of the request body, keyed with your API token (the oldest valid one, if the sales channel has several).", "in": "header", "name": "x-hive-signature", "required": true, "schema": { "type": "string", "examples": [ "a1b2c3d4e5f6..." ] } } }, "responses": { "BadRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "success": false, "errors": [ "bad request" ] } } } } }, "description": "The body is not valid JSON. Creating or updating an order and creating a SKU also answer this to an empty body." }, "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "success": false, "errors": [ "a record with this data already exists" ] } }, "duplicate_order": { "summary": "An order with this merchant_order_id already exists", "value": { "success": false, "errors": [ "a record with this data already exists" ], "metadata": { "id": 4962 } } } } } }, "description": "A record with the same data already exists" }, "Forbidden": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "success": false, "errors": [ "forbidden" ] } } } } }, "description": "The access token has expired, or its sales channel is not active" }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "success": false, "errors": [ "record not found" ] } } } } }, "description": "The record does not exist, or does not belong to you" }, "TooManyRequests": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "success": false, "errors": [ "rate limit exceeded" ] } } } } }, "description": "The rate limit is exceeded", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Rate-Limit-Max": { "$ref": "#/components/headers/RateLimitMax" }, "X-Rate-Limit-Used": { "$ref": "#/components/headers/RateLimitUsed" } } }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "success": false, "errors": [ "authentication required" ] } } } } }, "description": "The access token is missing or unknown" }, "UnprocessableEntity": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation": { "summary": "The data is invalid", "value": { "success": false, "errors": [ "Name can't be blank", "Merchant sku can't be blank" ] } }, "unknown_property": { "summary": "A property the endpoint does not know", "value": { "success": false, "errors": [ "unknown property: colour - available properties: id, merchant_sku_id, name" ] } } } } }, "description": "The data is invalid, or the action is not allowed in the record's current state" } }, "schemas": { "Error": { "additionalProperties": false, "description": "The body of every error response.", "properties": { "errors": { "description": "Human-readable error messages.", "items": { "type": "string" }, "type": "array" }, "metadata": { "additionalProperties": false, "description": "Details about the error. Only sent when an order with the same `merchant_order_id` already exists.", "properties": { "id": { "description": "The Hive ID of the existing order.", "format": "int64", "type": "integer" } }, "type": "object" }, "success": { "const": false, "description": "Always `false` for an error.", "type": "boolean" } }, "required": [ "success", "errors" ], "type": "object", "examples": [ { "success": false, "errors": [ "record not found" ] } ] }, "Pagination": { "additionalProperties": false, "description": "Where this page sits in the whole result.", "properties": { "current_page": { "description": "The number of this page, starting at 1.", "type": "integer" }, "item_count": { "description": "The total number of records across all pages.", "type": "integer" }, "items_per_page": { "description": "The page size (the `limit` in effect).", "type": "integer" }, "page_count": { "description": "The total number of pages.", "type": "integer" } }, "required": [ "current_page", "item_count", "page_count", "items_per_page" ], "type": "object", "examples": [ { "current_page": 1, "item_count": 2, "page_count": 1, "items_per_page": 20 } ] }, "Address": { "additionalProperties": false, "description": "A shipping address, with the recipient's contact details.", "properties": { "city": { "description": "City.", "type": [ "string", "null" ] }, "company": { "description": "Company name of the recipient.", "type": [ "string", "null" ] }, "country_code": { "description": "The 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. On input a country name is accepted too and converted to its code.", "type": [ "string", "null" ] }, "email": { "description": "Email address of the recipient.", "type": [ "string", "null" ] }, "first_name": { "description": "First name of the recipient.", "type": [ "string", "null" ] }, "full_name": { "description": "Full name of the recipient.", "type": [ "string", "null" ] }, "last_name": { "description": "Last name of the recipient.", "type": [ "string", "null" ] }, "line1": { "description": "Address line 1.", "type": [ "string", "null" ] }, "line2": { "description": "Address line 2.", "type": [ "string", "null" ] }, "parcel_point_id": { "description": "The parcel point to deliver to. Only [Sendcloud service point](https://api.sendcloud.dev/docs/sendcloud-public-api/branches/v2/service-points) IDs are supported.", "type": [ "string", "null" ] }, "phone": { "description": "Phone number of the recipient.", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal code.", "type": [ "string", "null" ] }, "province_or_state_code": { "description": "Province or state code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) subdivision code).", "type": [ "string", "null" ] } }, "required": [ "first_name", "last_name", "full_name", "email", "phone", "company", "line1", "line2", "city", "country_code", "postal_code", "parcel_point_id", "province_or_state_code" ], "type": "object", "examples": [ { "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "email": "john.doe@example.com", "phone": null, "company": null, "line1": "Kassaveti 69", "line2": null, "city": "Volos", "country_code": "GR", "postal_code": "38221", "parcel_point_id": null, "province_or_state_code": null } ] }, "AddressInput": { "additionalProperties": false, "description": "A shipping address. When an order is created, `full_name`, `line1`, `city`, `postal_code`, `country_code` and one of `first_name` or `last_name` are required. When an order is updated, the properties you send are merged into the current address.\n", "properties": { "city": { "description": "City.", "type": [ "string", "null" ] }, "company": { "description": "Company name of the recipient.", "type": [ "string", "null" ] }, "country_code": { "description": "The 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. A country name is accepted too and converted to its code.", "type": [ "string", "null" ] }, "email": { "description": "Email address of the recipient.", "type": [ "string", "null" ] }, "first_name": { "description": "First name of the recipient. Required if `last_name` is not given.", "type": [ "string", "null" ] }, "full_name": { "description": "Full name of the recipient.", "type": [ "string", "null" ] }, "last_name": { "description": "Last name of the recipient. Required if `first_name` is not given.", "type": [ "string", "null" ] }, "line1": { "description": "Address line 1.", "type": [ "string", "null" ] }, "line2": { "description": "Address line 2.", "type": [ "string", "null" ] }, "parcel_point_carrier_code": { "deprecated": true, "description": "Accepted for compatibility and ignored.", "type": [ "string", "null" ] }, "parcel_point_id": { "description": "The parcel point to deliver to. Only [Sendcloud service point](https://api.sendcloud.dev/docs/sendcloud-public-api/branches/v2/service-points) IDs are supported.", "type": [ "string", "null" ] }, "phone": { "description": "Phone number of the recipient.", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal code.", "type": [ "string", "null" ] }, "province_or_state_code": { "description": "Province or state code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) subdivision code).", "type": [ "string", "null" ] } }, "type": "object", "examples": [ { "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "line1": "Kassaveti 69", "city": "Volos", "country_code": "GR", "postal_code": "38221" } ] }, "Order": { "additionalProperties": false, "description": "An order of the sales channel.", "properties": { "carrier_preference": { "description": "The carrier the merchant prefers for delivering this order.", "type": [ "string", "null" ] }, "created_at": { "description": "When the order was placed, as sent by the merchant; the time Hive received it if none was sent.", "format": "date-time", "type": "string" }, "currency": { "description": "The 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the order's amounts.", "type": "string" }, "custom_metadata": { "description": "The custom metadata object sent by the merchant.", "type": [ "object", "null" ] }, "customer_order_number": { "description": "The order number the customer sees; the `merchant_order_id` when none was sent.", "type": [ "string", "null" ] }, "financial_status": { "description": "The financial status of the order.", "enum": [ "paid", "refunded", "pending", "failed", null ], "type": [ "string", "null" ] }, "id": { "description": "Hive's unique identifier for the order.", "format": "int64", "readOnly": true, "type": "integer" }, "items": { "description": "The order's line items, including items cancelled by an update.", "items": { "$ref": "#/components/schemas/OrderItem" }, "type": "array" }, "merchant_order_id": { "description": "The merchant's unique identifier for the order, unique within the sales channel.", "type": "string" }, "payment_method": { "description": "The payment method of the order. `COD` marks a Cash on Delivery order.", "type": [ "string", "null" ] }, "shipping_address": { "$ref": "#/components/schemas/Address", "description": "The order's shipping address and recipient." }, "status": { "description": "The order status:\n- `fulfillable`: Hive will fulfill the order. Orders created through the API are fulfillable by default.\n- `unfulfillable`: Hive will not fulfill the order, for example because it was cancelled or its destination country is blocked for the sales channel.\n- `fulfilled`: the order is fulfilled.\n- `on_hold`: fulfillment of the order is on hold.\n", "enum": [ "fulfillable", "unfulfillable", "fulfilled", "on_hold" ], "type": "string" }, "tags": { "description": "The order's tags.", "items": { "type": "string" }, "type": "array" }, "total_net_refunds_in_cents": { "description": "Refunds without tax, in cents.", "type": [ "integer", "null" ] }, "total_net_revenue_in_cents": { "description": "Revenue without tax (amount paid minus tax), in cents.", "type": [ "integer", "null" ] }, "total_price_in_cents": { "description": "The total price paid, in cents.", "type": "integer" }, "total_tax_in_cents": { "description": "The tax paid, in cents.", "type": [ "integer", "null" ] }, "total_tax_refunds_in_cents": { "description": "The tax part of the refunds, in cents.", "type": [ "integer", "null" ] } }, "required": [ "id", "merchant_order_id", "customer_order_number", "status", "carrier_preference", "created_at", "currency", "financial_status", "payment_method", "total_price_in_cents", "total_net_revenue_in_cents", "total_tax_in_cents", "total_net_refunds_in_cents", "total_tax_refunds_in_cents", "tags", "shipping_address", "items", "custom_metadata" ], "type": "object", "examples": [ { "id": 4962, "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106", "customer_order_number": "#1042", "status": "fulfillable", "carrier_preference": null, "created_at": "2022-11-01T17:42:07.409+01:00", "currency": "EUR", "financial_status": "paid", "payment_method": null, "total_price_in_cents": 2500, "total_net_revenue_in_cents": 2101, "total_tax_in_cents": 399, "total_net_refunds_in_cents": 0, "total_tax_refunds_in_cents": 0, "tags": [ "first_order" ], "shipping_address": { "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "email": "john.doe@example.com", "phone": null, "company": null, "line1": "Kassaveti 69", "line2": null, "city": "Volos", "country_code": "GR", "postal_code": "38221", "parcel_point_id": null, "province_or_state_code": null }, "items": [ { "sku_id": 9, "quantity": 1, "merchant_item_id": "1", "price_per_unit_in_cents": 2500, "price_per_unit_in_cents_with_discount": 2500, "merchant_sku_id": "28595522549341" } ], "custom_metadata": null } ] }, "OrderCreate": { "additionalProperties": false, "description": "The body for creating an order.", "properties": { "carrier_preference": { "description": "The carrier you prefer for delivering this order.", "type": [ "string", "null" ] }, "created_at": { "description": "When the order was placed, as an ISO 8601 date-time. Must not be in the future; defaults to the current time.", "type": [ "string", "null" ] }, "currency": { "description": "The 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the order's amounts. Defaults to `EUR`.", "type": [ "string", "null" ] }, "custom_metadata": { "description": "Any JSON object you want to store with the order.", "type": [ "object", "null" ] }, "customer_order_number": { "description": "The order number the customer sees, if it differs from `merchant_order_id`, which is the default.", "type": [ "string", "null" ] }, "financial_status": { "description": "The financial status of the order.", "enum": [ "paid", "refunded", "pending", "failed", null ], "type": [ "string", "null" ] }, "id": { "description": "Accepted and ignored; Hive assigns the ID." }, "items": { "description": "The order's line items. At least one is required, and each `merchant_item_id` must be unique within the order.", "items": { "$ref": "#/components/schemas/OrderItemInput" }, "type": "array" }, "merchant_order_id": { "description": "Your unique identifier for the order, unique within the sales channel.", "type": "string" }, "payment_method": { "description": "The payment method of the order. For a Cash on Delivery order, send a value containing `COD`; `total_price_in_cents` must then be greater than 0, because it is the amount the carrier collects at delivery.", "type": [ "string", "null" ] }, "shipping_address": { "$ref": "#/components/schemas/AddressInput", "description": "The order's shipping address and recipient." }, "status": { "description": "The order status to store. Leave it out; orders are created as `fulfillable`.", "enum": [ "fulfillable", "unfulfillable", "fulfilled", "on_hold", null ], "type": [ "string", "null" ] }, "tags": { "description": "Tags for the order, for example to trigger add-on rules. A single string is accepted as one tag.", "items": { "type": "string" }, "type": [ "array", "string", "null" ] }, "total_net_refunds_in_cents": { "description": "Refunds without tax, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_net_revenue_in_cents": { "description": "Revenue without tax, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_price_in_cents": { "description": "The total price paid, in cents. Required and greater than 0 for Cash on Delivery orders. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_tax_in_cents": { "description": "The tax paid, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_tax_refunds_in_cents": { "description": "The tax part of the refunds, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] } }, "required": [ "merchant_order_id", "shipping_address", "items" ], "type": "object", "examples": [ { "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106", "customer_order_number": "#1042", "currency": "EUR", "financial_status": "paid", "total_price_in_cents": 2500, "tags": [ "first_order" ], "shipping_address": { "first_name": "John", "last_name": "Doe", "full_name": "John Doe", "line1": "Kassaveti 69", "city": "Volos", "country_code": "GR", "postal_code": "38221" }, "items": [ { "merchant_item_id": "1", "merchant_sku_id": "28595522549341", "quantity": 1, "price_per_unit_in_cents": 2500 } ] } ] }, "OrderUpdate": { "additionalProperties": false, "description": "The body for updating an order. Every property is optional; the ones you leave out keep their value. `null` does not clear `carrier_preference`, `currency`, `custom_metadata`, `financial_status` or `payment_method`: they keep their value. A `null` `customer_order_number` resets it to `merchant_order_id`, and a `null` amount sets it to 0.\n", "properties": { "carrier_preference": { "description": "The carrier you prefer for delivering this order.", "type": [ "string", "null" ] }, "created_at": { "description": "When the order was placed, as an ISO 8601 date-time. Must not be in the future.", "type": [ "string", "null" ] }, "currency": { "description": "The 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the order's amounts.", "type": [ "string", "null" ] }, "custom_metadata": { "description": "Any JSON object you want to store with the order. Replaces the stored object; `null` keeps it.", "type": [ "object", "null" ] }, "customer_order_number": { "description": "The order number the customer sees. `null` resets it to `merchant_order_id`.", "type": [ "string", "null" ] }, "financial_status": { "description": "The financial status of the order.", "enum": [ "paid", "refunded", "pending", "failed", null ], "type": [ "string", "null" ] }, "id": { "description": "Accepted and ignored; Hive assigns the ID." }, "items": { "description": "The complete list of the order's line items. Items are matched to the existing ones by `merchant_item_id`; existing items missing from the list are cancelled.", "items": { "$ref": "#/components/schemas/OrderItemInput" }, "type": "array" }, "merchant_order_id": { "description": "Your unique identifier for the order. Must be the order's current value; a different one does not rename the order but addresses the order with that value.", "type": "string" }, "payment_method": { "description": "The payment method of the order. A value containing `COD` marks a Cash on Delivery order, which needs a `total_price_in_cents` greater than 0.", "type": [ "string", "null" ] }, "shipping_address": { "$ref": "#/components/schemas/AddressInput", "description": "The order's shipping address and recipient." }, "status": { "description": "The order status to store. Leave it out; use `PUT /orders/{id}/cancel` to cancel an order.", "enum": [ "fulfillable", "unfulfillable", "fulfilled", "on_hold", null ], "type": [ "string", "null" ] }, "tags": { "description": "Tags for the order, replacing the current ones. A single string is accepted as one tag.", "items": { "type": "string" }, "type": [ "array", "string", "null" ] }, "total_net_refunds_in_cents": { "description": "Refunds without tax, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_net_revenue_in_cents": { "description": "Revenue without tax, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_price_in_cents": { "description": "The total price paid, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_tax_in_cents": { "description": "The tax paid, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_tax_refunds_in_cents": { "description": "The tax part of the refunds, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] } }, "type": "object", "examples": [ { "financial_status": "refunded", "total_net_refunds_in_cents": 2101, "total_tax_refunds_in_cents": 399 } ] }, "OrderItem": { "additionalProperties": false, "description": "A line item of an order.", "properties": { "merchant_item_id": { "description": "The merchant's identifier for the line item, unique within the order.", "type": "string" }, "merchant_sku_id": { "description": "The merchant's SKU ID (`merchant_sku_id` of the SKU).", "type": [ "string", "null" ] }, "price_per_unit_in_cents": { "description": "The price of one unit, in cents.", "type": "integer" }, "price_per_unit_in_cents_with_discount": { "description": "The discounted price of one unit, in cents.", "type": [ "integer", "null" ] }, "quantity": { "description": "The number of units.", "type": "integer" }, "sku_id": { "description": "Hive's ID of the SKU.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "sku_id", "quantity", "merchant_item_id", "price_per_unit_in_cents", "price_per_unit_in_cents_with_discount", "merchant_sku_id" ], "type": "object", "examples": [ { "sku_id": 9, "quantity": 1, "merchant_item_id": "1", "price_per_unit_in_cents": 2500, "price_per_unit_in_cents_with_discount": 2500, "merchant_sku_id": "28595522549341" } ] }, "OrderItemInput": { "additionalProperties": false, "description": "A line item of an order. Give the SKU by `sku_id` or by `merchant_sku_id`; when both are given, `sku_id` is used.", "properties": { "merchant_item_id": { "description": "Your identifier for the line item, unique within the order.", "type": "string" }, "merchant_sku_id": { "description": "Your SKU ID (`merchant_sku_id` of the SKU). Required if `sku_id` is not given.", "type": [ "string", "null" ] }, "price_per_unit_in_cents": { "description": "The price of one unit, in cents; 0 if left out. Used for customs documents, return labels and the amount to collect for Cash on Delivery orders. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "price_per_unit_in_cents_with_discount": { "description": "The discounted price of one unit, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "quantity": { "description": "The number of units. Must be greater than 0. A string of digits is accepted too.", "minimum": 1, "pattern": "^-?[0-9]+$", "type": [ "integer", "string" ] }, "sku_id": { "description": "Hive's ID of the SKU. Required if `merchant_sku_id` is not given. A string of digits is accepted too.", "format": "int64", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] } }, "required": [ "merchant_item_id", "quantity" ], "type": "object", "examples": [ { "merchant_item_id": "1", "merchant_sku_id": "28595522549341", "quantity": 1, "price_per_unit_in_cents": 2500 } ] }, "RestockingShipment": { "additionalProperties": false, "description": "A restocking shipment, an inbound delivery of stock to a Hive warehouse.", "properties": { "barcode": { "description": "The barcode that identifies the restocking shipment at the warehouse.", "readOnly": true, "type": "string" }, "delivery_option": { "description": "How the shipment is delivered to the warehouse.", "enum": [ "postal", "courier", "dropoff", "hive_freight" ], "type": "string" }, "estimated_arrival_date": { "description": "The estimated arrival date.", "format": "date", "type": [ "string", "null" ] }, "id": { "description": "Hive's unique identifier for the restocking shipment.", "format": "int64", "readOnly": true, "type": "integer" }, "merchant_id": { "description": "Hive's ID of the merchant the restocking shipment belongs to.", "format": "int64", "readOnly": true, "type": "integer" }, "po_number": { "description": "Purchase order number.", "type": [ "string", "null" ] }, "restocking_shipment_items": { "description": "The items in the shipment.", "items": { "$ref": "#/components/schemas/RestockingShipmentItem" }, "type": "array" }, "status": { "description": "The restocking shipment status:\n- `created`: created and not shipped yet.\n- `shipped`: on the way to the warehouse. Restocking shipments created through the API start here.\n- `delivered`: delivered to the warehouse, but its content is not checked yet.\n- `arrived`: Hive completed the arrival documentation: the packing slip is checked, and pictures of the shipment and its documents are uploaded.\n- `processing`: being unpacked, its items are being put into storage.\n- `restocked`: fully processed, all its items are in storage.\n- `on_hold`: processing is on hold.\n- `cancelled`: cancelled.\n", "enum": [ "created", "shipped", "delivered", "arrived", "processing", "restocked", "on_hold", "cancelled" ], "readOnly": true, "type": "string" }, "supplier_name": { "description": "Supplier name.", "type": [ "string", "null" ] }, "tracking_code": { "description": "The shipment's tracking code.", "type": [ "string", "null" ] }, "warehouse_id": { "description": "Hive's ID of the destination warehouse.", "format": "int64", "type": "integer" } }, "required": [ "id", "merchant_id", "warehouse_id", "estimated_arrival_date", "delivery_option", "tracking_code", "po_number", "supplier_name", "status", "barcode", "restocking_shipment_items" ], "type": "object", "examples": [ { "id": 13, "merchant_id": 1, "warehouse_id": 71, "estimated_arrival_date": "2022-12-01", "delivery_option": "postal", "tracking_code": "1234567", "po_number": null, "supplier_name": null, "status": "restocked", "barcode": "RS.13", "restocking_shipment_items": [ { "id": 15, "arrived_quantity": 4, "damaged_quantity": 1, "missing_quantity": 5, "remarks": null, "total_cost_in_cents": null, "announced_quantity": 10, "restocked_quantity": 4, "sku_id": 558, "merchant_sku_id": "MORPH-II", "inventory_batches": [ { "id": 827, "name": "Morph II - 827", "tracking_code": "A01234", "lot_number": null, "production_date": null, "expiry_date": "2023-12-30", "arrived_quantity": 3 }, { "id": 828, "name": "Morph II - 828", "tracking_code": "B56789", "lot_number": null, "production_date": null, "expiry_date": "2024-02-15", "arrived_quantity": 1 } ] } ] } ] }, "RestockingShipmentCreate": { "additionalProperties": true, "description": "The body for creating a restocking shipment. Properties not listed here are ignored.", "properties": { "delivery_option": { "description": "How the shipment is delivered to the warehouse.", "enum": [ "postal", "courier", "dropoff", "hive_freight" ], "type": "string" }, "estimated_arrival_date": { "description": "The estimated arrival date. A date-time is accepted too; its date is used.", "type": "string" }, "po_number": { "description": "Purchase order number.", "type": [ "string", "null" ] }, "restocking_shipment_items": { "description": "The items in the shipment.", "items": { "$ref": "#/components/schemas/RestockingShipmentItemInput" }, "type": "array" }, "supplier_name": { "description": "Supplier name.", "type": [ "string", "null" ] }, "tracking_code": { "description": "The shipment's tracking code.", "type": [ "string", "null" ] }, "warehouse_id": { "description": "Hive's ID of the destination warehouse, one of the merchant's warehouses (see `GET /warehouses`). A string of digits is accepted too.", "format": "int64", "pattern": "^-?[0-9]+$", "type": [ "integer", "string" ] } }, "required": [ "warehouse_id", "estimated_arrival_date", "delivery_option" ], "type": "object", "examples": [ { "warehouse_id": 71, "estimated_arrival_date": "2022-12-01", "delivery_option": "postal", "tracking_code": "1234567", "restocking_shipment_items": [ { "sku_id": 558, "announced_quantity": 12 } ] } ] }, "RestockingShipmentUpdate": { "additionalProperties": true, "description": "The body for updating a restocking shipment. The top-level properties you leave out keep their value; `restocking_shipment_items` replaces the whole item list, and leaving it out removes every item. Properties not listed here are ignored.\n", "properties": { "delivery_option": { "description": "How the shipment is delivered to the warehouse.", "enum": [ "postal", "courier", "dropoff", "hive_freight" ], "type": "string" }, "estimated_arrival_date": { "description": "The estimated arrival date. A date-time is accepted too; its date is used.", "type": "string" }, "po_number": { "description": "Purchase order number.", "type": [ "string", "null" ] }, "restocking_shipment_items": { "description": "The complete list of items in the shipment, replacing the current one.", "items": { "$ref": "#/components/schemas/RestockingShipmentItemInput" }, "type": "array" }, "supplier_name": { "description": "Supplier name.", "type": [ "string", "null" ] }, "tracking_code": { "description": "The shipment's tracking code.", "type": [ "string", "null" ] }, "warehouse_id": { "description": "Hive's ID of the destination warehouse, one of the merchant's warehouses (see `GET /warehouses`). A string of digits is accepted too.", "format": "int64", "pattern": "^-?[0-9]+$", "type": [ "integer", "string" ] } }, "type": "object", "examples": [ { "estimated_arrival_date": "2022-12-05", "restocking_shipment_items": [ { "sku_id": 558, "announced_quantity": 12 } ] } ] }, "RestockingShipmentItem": { "additionalProperties": false, "description": "An item of a restocking shipment.", "properties": { "announced_quantity": { "description": "The quantity announced for the shipment.", "type": [ "integer", "null" ] }, "arrived_quantity": { "description": "The quantity counted when the shipment arrived at the warehouse. Can differ from `restocked_quantity`.", "readOnly": true, "type": [ "integer", "null" ] }, "damaged_quantity": { "description": "The quantity that arrived damaged.", "readOnly": true, "type": [ "integer", "null" ] }, "id": { "description": "Hive's unique identifier for the item.", "format": "int64", "readOnly": true, "type": "integer" }, "inventory_batches": { "description": "The inventory batches the item was restocked into, once it is restocked. Always empty in the responses of `POST /restocking_shipments` and `PUT /restocking_shipments/{id}`.", "items": { "$ref": "#/components/schemas/RestockingShipmentInventoryBatch" }, "readOnly": true, "type": "array" }, "merchant_sku_id": { "description": "The merchant's SKU ID (`merchant_sku_id` of the SKU).", "type": [ "string", "null" ] }, "missing_quantity": { "description": "The announced quantity that did not arrive.", "readOnly": true, "type": [ "integer", "null" ] }, "remarks": { "description": "Free-text remarks.", "type": [ "string", "null" ] }, "restocked_quantity": { "description": "The quantity put into sellable stock, the \"restocked\" figure of the Hive app. Can differ from `arrived_quantity`, the count at arrival.", "readOnly": true, "type": "integer" }, "sku_id": { "description": "Hive's ID of the SKU.", "format": "int64", "type": [ "integer", "null" ] }, "total_cost_in_cents": { "description": "The total cost of the item, in cents.", "type": [ "integer", "null" ] } }, "required": [ "id", "arrived_quantity", "damaged_quantity", "missing_quantity", "remarks", "total_cost_in_cents", "announced_quantity", "restocked_quantity", "sku_id", "merchant_sku_id", "inventory_batches" ], "type": "object", "examples": [ { "id": 15, "arrived_quantity": 0, "damaged_quantity": 0, "missing_quantity": 0, "remarks": null, "total_cost_in_cents": null, "announced_quantity": 12, "restocked_quantity": 0, "sku_id": 558, "merchant_sku_id": "MORPH-II", "inventory_batches": [] } ] }, "RestockingShipmentItemInput": { "additionalProperties": true, "description": "An item of a restocking shipment. Give the SKU by `sku_id` or by `merchant_sku_id`; when both are given, `sku_id` is used. Properties not listed here are ignored.", "properties": { "announced_quantity": { "description": "The quantity you are sending. Must be greater than 0 when given. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "inventory_batch_id": { "description": "Hive's ID of the inventory batch the units belong to, for a batch-tracked SKU. A string of digits is accepted too.", "format": "int64", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "merchant_sku_id": { "description": "Your SKU ID (`merchant_sku_id` of the SKU). Required if `sku_id` is not given.", "type": [ "string", "null" ] }, "remarks": { "description": "Free-text remarks.", "type": [ "string", "null" ] }, "sku_id": { "description": "Hive's ID of the SKU. Required if `merchant_sku_id` is not given. A string of digits is accepted too.", "format": "int64", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "total_cost_in_cents": { "description": "The total cost of the item, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] } }, "type": "object", "examples": [ { "sku_id": 558, "announced_quantity": 12, "total_cost_in_cents": 12000 } ] }, "RestockingShipmentInventoryBatch": { "additionalProperties": false, "description": "An inventory batch that items of a restocking shipment were restocked into.", "properties": { "arrived_quantity": { "description": "The quantity of the item restocked into this batch.", "type": "integer" }, "expiry_date": { "description": "The batch's expiry date.", "format": "date", "type": [ "string", "null" ] }, "id": { "description": "Hive's unique identifier for the batch.", "format": "int64", "type": "integer" }, "lot_number": { "description": "The batch's lot number.", "type": [ "string", "null" ] }, "name": { "description": "The batch's name.", "type": [ "string", "null" ] }, "production_date": { "description": "The batch's production date.", "format": "date", "type": [ "string", "null" ] }, "tracking_code": { "description": "The batch's tracking code.", "type": [ "string", "null" ] } }, "required": [ "id", "name", "tracking_code", "lot_number", "production_date", "expiry_date", "arrived_quantity" ], "type": "object", "examples": [ { "id": 827, "name": "Morph II - 827", "tracking_code": "A01234", "lot_number": "L-2023-11", "production_date": "2023-06-30", "expiry_date": "2023-12-30", "arrived_quantity": 3 } ] }, "Return": { "additionalProperties": false, "description": "A return of an order.", "properties": { "carrier": { "description": "The carrier that brought the return back.", "type": [ "string", "null" ] }, "completed_handling_at": { "description": "When handling of the return was completed.", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the return was created.", "format": "date-time", "type": "string" }, "id": { "description": "Hive's unique identifier for the return.", "format": "int64", "type": "integer" }, "order": { "$ref": "#/components/schemas/ReturnOrder", "description": "The order the return belongs to." }, "photos": { "description": "Photos of the returned parcel.", "items": { "$ref": "#/components/schemas/ReturnPhoto" }, "type": "array" }, "received_at": { "description": "When the return was received at the warehouse.", "format": "date-time", "type": [ "string", "null" ] }, "return_items": { "description": "The items the customer announced through the Customer Portal. Empty if the return did not come through the Customer Portal.", "items": { "$ref": "#/components/schemas/ReturnItem" }, "type": "array" }, "return_line_items": { "description": "The items that were handled at the warehouse. Empty until the return is handled.", "items": { "$ref": "#/components/schemas/ReturnLineItem" }, "type": "array" }, "return_reason": { "description": "Why the parcel came back. Can be `null` or an empty string when no reason is recorded.", "enum": [ "customer_return", "not_picked_up", "invalid_address", "rejected_by_customer", "customs_documents_missing", "return_label_in_box", "other", "", null ], "type": [ "string", "null" ] }, "return_reason_type": { "description": "The kind of return:\n- `active`: a customer return, the customer shipped the parcel back.\n- `passive`: a carrier return, the customer never received the parcel and the carrier sent it back, for example because of an invalid address, a parcel not picked up, damage or missing customs documents.\n- `null` or an empty string: the return was created before it was processed and did not come through the Customer Portal. Customer Portal returns are always `active`.\n", "enum": [ "active", "passive", "", null ], "type": [ "string", "null" ] }, "started_processing_at": { "description": "When processing of the return started at the warehouse.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "The return status:\n- `requested`: requested through the Customer Portal and waiting for approval.\n- `on_the_way`: on the way to the warehouse.\n- `arrived`: arrived at the warehouse.\n- `processing`: being processed.\n- `action_required`: waiting for guidance from the merchant.\n- `handling_completed`: processing is completed.\n- `cancelled`: cancelled.\n", "enum": [ "requested", "on_the_way", "arrived", "processing", "action_required", "handling_completed", "cancelled" ], "type": "string" }, "tracking_code": { "description": "The tracking number the carrier assigned to the return.", "type": [ "string", "null" ] }, "tracking_url": { "description": "The carrier's tracking page for the return.", "type": [ "string", "null" ] } }, "required": [ "id", "return_reason_type", "return_reason", "status", "tracking_code", "tracking_url", "carrier", "created_at", "received_at", "started_processing_at", "completed_handling_at", "order", "photos", "return_items", "return_line_items" ], "type": "object", "examples": [ { "id": 70047, "return_reason_type": "active", "return_reason": "customer_return", "status": "handling_completed", "tracking_code": "TC123456789", "tracking_url": "https://example.org/package?trackingNumber=TC123456789", "carrier": "ExampleCarrier", "created_at": "2023-05-18T09:38:18.999+02:00", "received_at": "2023-05-19T10:38:18.999+02:00", "started_processing_at": "2023-05-20T11:38:18.999+02:00", "completed_handling_at": "2023-05-21T12:38:18.999+02:00", "order": { "id": 1230221, "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106", "name": "#DE12345" }, "photos": [ { "id": 115234, "photo_type": "outside", "image_url": "https://example.org/photos/115234.jpg" } ], "return_items": [ { "id": 27890, "quantity": 1, "customer_return_message": "I ordered a red pencil but got a green one", "customer_return_reason": "incorrect_product_arrived", "sku": { "id": 123085, "merchant_sku_id": "ABC123" } } ], "return_line_items": [ { "id": 10456, "inventory_batch_id": 123, "return_item_id": 27890, "condition": "A", "follow_up_action": "restock", "quantity": 1, "photos": [ { "id": 117781, "image_url": "https://example.org/photos/117781.jpg" } ], "sku": { "id": 123085, "merchant_sku_id": "ABC123" } } ] } ] }, "ReturnItem": { "additionalProperties": false, "description": "An item the customer announced for return through the Customer Portal.", "properties": { "customer_return_message": { "description": "Details the customer gave about the return.", "type": [ "string", "null" ] }, "customer_return_reason": { "description": "The reason the customer chose.", "type": [ "string", "null" ] }, "id": { "description": "Hive's unique identifier for the return item.", "format": "int64", "type": "integer" }, "quantity": { "description": "The quantity announced.", "type": [ "integer", "null" ] }, "sku": { "$ref": "#/components/schemas/ReturnSku", "description": "The SKU of the returned item." } }, "required": [ "id", "quantity", "customer_return_message", "customer_return_reason", "sku" ], "type": "object", "examples": [ { "id": 27890, "quantity": 1, "customer_return_message": "I ordered a red pencil but got a green one", "customer_return_reason": "incorrect_product_arrived", "sku": { "id": 123085, "merchant_sku_id": "ABC123" } } ] }, "ReturnLineItem": { "additionalProperties": false, "description": "An item handled at the warehouse as part of a return.", "properties": { "condition": { "description": "The condition of the returned item:\n- `A`: unused, in its original packaging.\n- `B`: unused, with missing or damaged packaging.\n- `C`: used or damaged.\n", "enum": [ "A", "B", "C", "", null ], "type": [ "string", "null" ] }, "follow_up_action": { "description": "What happens to the item, chosen by the merchant's return rules.", "enum": [ "restock", "dispose", "send_back", "", null ], "type": [ "string", "null" ] }, "id": { "description": "Hive's unique identifier for the line item.", "format": "int64", "type": "integer" }, "inventory_batch_id": { "description": "Hive's ID of the inventory batch the item is restocked into, when `follow_up_action` is `restock` and the SKU is batch-tracked.", "format": "int64", "type": [ "integer", "null" ] }, "photos": { "description": "Photos of the returned item.", "items": { "$ref": "#/components/schemas/ReturnLineItemPhoto" }, "type": "array" }, "quantity": { "description": "The quantity returned of this SKU.", "type": "integer" }, "return_item_id": { "description": "Hive's ID of the announced return item this line item corresponds to. Empty when the return did not come through the Customer Portal.", "format": "int64", "type": [ "integer", "null" ] }, "sku": { "$ref": "#/components/schemas/ReturnSku", "description": "The SKU of the returned item." } }, "required": [ "id", "inventory_batch_id", "return_item_id", "condition", "follow_up_action", "quantity", "photos", "sku" ], "type": "object", "examples": [ { "id": 10456, "inventory_batch_id": 123, "return_item_id": 27890, "condition": "A", "follow_up_action": "restock", "quantity": 1, "photos": [], "sku": { "id": 123085, "merchant_sku_id": "ABC123" } } ] }, "ReturnLineItemPhoto": { "additionalProperties": false, "description": "A photo of a returned item.", "properties": { "id": { "description": "Hive's unique identifier for the photo.", "format": "int64", "type": "integer" }, "image_url": { "description": "A publicly accessible URL of the photo.", "type": [ "string", "null" ] } }, "required": [ "id", "image_url" ], "type": "object", "examples": [ { "id": 117781, "image_url": "https://example.org/photos/117781.jpg" } ] }, "ReturnOrder": { "additionalProperties": false, "description": "The order a return belongs to.", "properties": { "id": { "description": "Hive's ID of the order. `GET /orders/{id}` finds it when the order belongs to the token's sales channel and was not created manually.", "format": "int64", "type": "integer" }, "merchant_order_id": { "description": "The merchant's identifier for the order.", "type": "string" }, "name": { "description": "The order number the customer sees.", "type": [ "string", "null" ] } }, "required": [ "id", "merchant_order_id", "name" ], "type": "object", "examples": [ { "id": 1230221, "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106", "name": "#DE12345" } ] }, "ReturnPhoto": { "additionalProperties": false, "description": "A photo of a returned parcel.", "properties": { "id": { "description": "Hive's unique identifier for the photo.", "format": "int64", "type": "integer" }, "image_url": { "description": "A publicly accessible URL of the photo.", "type": [ "string", "null" ] }, "photo_type": { "description": "What the photo shows, usually `inside` or `outside` of the parcel.", "type": [ "string", "null" ] } }, "required": [ "id", "photo_type", "image_url" ], "type": "object", "examples": [ { "id": 115234, "photo_type": "outside", "image_url": "https://example.org/photos/115234.jpg" } ] }, "ReturnSku": { "additionalProperties": false, "description": "The SKU of a returned item.", "properties": { "id": { "description": "Hive's ID of the SKU.", "format": "int64", "type": "integer" }, "merchant_sku_id": { "description": "The merchant's SKU ID.", "type": [ "string", "null" ] } }, "required": [ "id", "merchant_sku_id" ], "type": "object", "examples": [ { "id": 123085, "merchant_sku_id": "ABC123" } ] }, "Shipment": { "additionalProperties": false, "description": "An outbound shipment of an order.", "properties": { "created_at": { "description": "When the shipment was created.", "format": "date-time", "type": "string" }, "delivered_at": { "description": "When the shipment was delivered.", "format": "date-time", "type": [ "string", "null" ] }, "delivery_status": { "description": "The latest delivery status reported by the carrier, `null` until there is one:\n- `Information transmitted to the carrier`: marked as shipped, no status from the carrier yet.\n- `In transit`: on the way to the carrier's hub.\n- `Out for delivery`: left the carrier's hub and is being delivered.\n- `Delivered`: delivered.\n- `Awaiting customer pickup`: waiting for the customer at a pickup point.\n- `Returned to sender`: the carrier is returning it to the sender.\n- `Return initiated`: a return was initiated.\n- `Action required`: something unusual happened, such as a failed delivery attempt, a lost parcel or an address problem.\n", "type": [ "string", "null" ], "examples": [ "Delivered" ] }, "id": { "description": "Hive's unique identifier for the shipment.", "format": "int64", "type": "integer" }, "items": { "description": "The items in the shipment.", "items": { "$ref": "#/components/schemas/ShipmentItem" }, "type": "array" }, "merchant_order_id": { "description": "The merchant's identifier for the shipment's order.", "type": "string" }, "order_id": { "description": "Hive's ID of the shipment's order. `GET /orders/{id}` finds it unless the order was created manually.", "format": "int64", "type": "integer" }, "shipment_provider": { "description": "The carrier's name.", "type": [ "string", "null" ] }, "shipped_at": { "description": "When the shipment was shipped.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "The fulfillment status of the shipment. `GET /shipments` only returns `shipped` shipments; the `shipment_status_updated` webhook sends every status.\n- `created`, `waiting_for_picking`: waiting to be picked.\n- `on_hold`: on hold, for example because fulfillment starts later, or because of an address problem or missing stock.\n- `picking_assigned`: a warehouse employee took on picking it.\n- `in_picking`: being picked.\n- `picked`: picked, ready for packing.\n- `in_packing`: being packed.\n- `packed`: packed, ready for shipping.\n- `in_shipping`: being shipped.\n- `shipped`: labelled and left the packing station, waiting for or already picked up by the carrier.\n- `cancelled`: cancelled, it will not be fulfilled.\n- `ignored`: will not be fulfilled by Hive.\n", "enum": [ "created", "waiting_for_picking", "on_hold", "picking_assigned", "in_picking", "picked", "in_packing", "packed", "in_shipping", "shipped", "cancelled", "ignored" ], "type": "string" }, "tracking_number": { "description": "The tracking number the carrier assigned.", "type": [ "string", "null" ] }, "tracking_url": { "description": "The carrier's tracking page for the shipment.", "type": [ "string", "null" ] }, "updated_at": { "description": "When the shipment was last updated.", "format": "date-time", "type": "string" }, "warehouse_id": { "description": "Hive's ID of the warehouse that fulfills the shipment.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "tracking_url", "status", "delivery_status", "created_at", "updated_at", "shipped_at", "delivered_at", "warehouse_id", "order_id", "merchant_order_id", "shipment_provider", "tracking_number", "items" ], "type": "object", "examples": [ { "id": 170, "tracking_url": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=CR123456789DE", "status": "shipped", "delivery_status": "Delivered", "created_at": "2022-06-04T03:17:25.533+02:00", "updated_at": "2022-07-22T16:53:31.388+02:00", "shipped_at": "2022-06-04T07:53:20.511+02:00", "delivered_at": "2022-06-06T22:17:46.000+02:00", "warehouse_id": 22, "order_id": 575, "merchant_order_id": "20220604-383", "shipment_provider": "DHL", "tracking_number": "CR123456789DE", "items": [ { "id": 201, "quantity": 1, "merchant_item_id": "QWERTY0987", "sku": { "id": 123000, "merchant_sku_id": "ABC123" }, "serial_numbers": [ { "serial_number": "1234567890" } ], "batches": [ { "quantity": 1, "id": 827, "lot_number": null, "production_date": null, "expiry_date": "2023-06-04", "name": "Batch 1", "tracking_code": "ABC123" } ] } ] } ] }, "ShipmentItem": { "additionalProperties": false, "description": "An item in a shipment. Items whose SKU is unknown to the sales channel are left out.", "properties": { "batches": { "description": "The inventory batches the item was taken from. Only recorded for batch-tracked SKUs and for batches the merchant chose.", "items": { "$ref": "#/components/schemas/ShipmentItemBatch" }, "type": "array" }, "id": { "description": "Hive's unique identifier for the shipment item.", "format": "int64", "type": "integer" }, "merchant_item_id": { "description": "The `merchant_item_id` of the order line item. `null` for items that were not order line items, such as add-ons added by add-on rules.", "type": [ "string", "null" ] }, "quantity": { "description": "The number of units.", "type": [ "integer", "null" ] }, "serial_numbers": { "description": "The serial numbers recorded for the item.", "items": { "$ref": "#/components/schemas/ShipmentItemSerialNumber" }, "type": "array" }, "sku": { "$ref": "#/components/schemas/ShipmentItemSku", "description": "The SKU of the shipment item." } }, "required": [ "id", "quantity", "merchant_item_id", "sku", "serial_numbers", "batches" ], "type": "object", "examples": [ { "id": 202, "quantity": 2, "merchant_item_id": "QWERTY6543", "sku": { "id": 123001, "merchant_sku_id": "DEF456" }, "serial_numbers": [], "batches": [] } ] }, "ShipmentItemBatch": { "additionalProperties": false, "description": "An inventory batch a shipment item was taken from.", "properties": { "expiry_date": { "description": "The batch's expiry date.", "format": "date", "type": [ "string", "null" ] }, "id": { "description": "Hive's unique identifier for the batch.", "format": "int64", "type": "integer" }, "lot_number": { "description": "The batch's lot number.", "type": [ "string", "null" ] }, "name": { "description": "The batch's name.", "type": [ "string", "null" ] }, "production_date": { "description": "The batch's production date.", "format": "date", "type": [ "string", "null" ] }, "quantity": { "description": "The number of units taken from this batch.", "type": "integer" }, "tracking_code": { "description": "The batch's tracking code.", "type": [ "string", "null" ] } }, "required": [ "quantity", "id", "lot_number", "production_date", "expiry_date", "name", "tracking_code" ], "type": "object", "examples": [ { "quantity": 1, "id": 827, "lot_number": "L-2023-05", "production_date": "2023-01-04", "expiry_date": "2023-06-04", "name": "Batch 1", "tracking_code": "ABC123" } ] }, "ShipmentItemSerialNumber": { "additionalProperties": false, "description": "A serial number recorded for a shipment item.", "properties": { "serial_number": { "description": "The serial number.", "type": [ "string", "null" ] } }, "required": [ "serial_number" ], "type": "object", "examples": [ { "serial_number": "1234567890" } ] }, "ShipmentItemSku": { "additionalProperties": false, "description": "The SKU of a shipment item.", "properties": { "id": { "description": "Hive's ID of the SKU in the sales channel.", "format": "int64", "type": "integer" }, "merchant_sku_id": { "description": "The merchant's SKU ID.", "type": [ "string", "null" ] } }, "required": [ "id", "merchant_sku_id" ], "type": "object", "examples": [ { "id": 123000, "merchant_sku_id": "ABC123" } ] }, "Sku": { "additionalProperties": false, "description": "A SKU of the sales channel, with its current inventory.", "properties": { "barcode": { "description": "The SKU's barcode.", "type": [ "string", "null" ] }, "batch_tracking_enabled": { "description": "Whether inventory of this SKU is tracked per batch.", "type": [ "boolean", "null" ] }, "cost_in_cent": { "deprecated": true, "description": "The same value as `cost_in_cents`, which replaces it.", "type": [ "integer", "null" ] }, "cost_in_cents": { "description": "The cost (not the price) of one unit, in cents, in the sales channel's currency.", "type": [ "integer", "null" ] }, "country_code_of_origin": { "description": "The 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code of the country of origin.", "type": [ "string", "null" ] }, "created_at": { "description": "When the SKU was created.", "format": "date-time", "readOnly": true, "type": "string" }, "dangerous_good": { "description": "Whether the SKU is classified as a dangerous good.", "readOnly": true, "type": "boolean" }, "fulfilled_by": { "description": "Who fulfills this SKU.", "enum": [ "hive", "other", "new" ], "readOnly": true, "type": "string" }, "h_codes": { "description": "The hazard statement codes (H codes) of the SKU's hazardous good classifications.", "items": { "type": "string" }, "readOnly": true, "type": "array" }, "hazardous_good": { "description": "Whether the SKU is classified as a hazardous good.", "readOnly": true, "type": "boolean" }, "hs_code": { "description": "The [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System) code.", "type": [ "string", "null" ] }, "id": { "description": "Hive's unique identifier for the SKU.", "format": "int64", "readOnly": true, "type": "integer" }, "image_url": { "description": "A publicly accessible URL of an image of the SKU.", "type": [ "string", "null" ] }, "inventory": { "$ref": "#/components/schemas/SkuInventory", "description": "The current inventory across all warehouses." }, "inventory_batches": { "description": "The current stock per inventory batch.", "items": { "$ref": "#/components/schemas/SkuInventoryBatch" }, "readOnly": true, "type": "array" }, "inventory_per_warehouse": { "description": "The current inventory per warehouse.", "items": { "$ref": "#/components/schemas/SkuInventoryPerWarehouse" }, "readOnly": true, "type": "array" }, "merchant_sku_id": { "description": "The merchant's identifier for the SKU, unique within the sales channel. Always set for SKUs created through the API.", "type": [ "string", "null" ] }, "name": { "description": "The SKU's name. Always set for SKUs created through the API.", "type": [ "string", "null" ] }, "status": { "description": "The SKU's status. `DELETE /skus/{id}` sets it to `deleted`; creating or updating the SKU sets it back to `active`.", "enum": [ "active", "archived", "draft", "deleted" ], "readOnly": true, "type": "string" }, "un_numbers": { "description": "The UN numbers of the SKU's dangerous good classifications.", "items": { "type": "string" }, "readOnly": true, "type": "array" }, "weight_in_kg": { "description": "The weight of one unit, in kilograms; 0 when unknown.", "type": "number" } }, "required": [ "id", "name", "country_code_of_origin", "hs_code", "status", "created_at", "cost_in_cent", "cost_in_cents", "weight_in_kg", "merchant_sku_id", "image_url", "barcode", "batch_tracking_enabled", "fulfilled_by", "dangerous_good", "un_numbers", "hazardous_good", "h_codes", "inventory", "inventory_per_warehouse", "inventory_batches" ], "type": "object", "examples": [ { "id": 9, "name": "Morph II", "country_code_of_origin": "DE", "hs_code": "950300", "status": "active", "created_at": "2022-08-10T17:53:04.822+02:00", "cost_in_cent": 1200, "cost_in_cents": 1200, "weight_in_kg": 0.3, "merchant_sku_id": "2218061549136", "image_url": "https://example.com/image.png", "barcode": "2218061549136", "batch_tracking_enabled": true, "fulfilled_by": "hive", "dangerous_good": true, "un_numbers": [ "UN3481" ], "hazardous_good": false, "h_codes": [], "inventory": { "stocked": 6760, "reserved": 0, "total": 6760 }, "inventory_per_warehouse": [ { "warehouse_id": 22, "stocked": 6720, "reserved": 0, "total": 6720 }, { "warehouse_id": 38, "stocked": 40, "reserved": 0, "total": 40 } ], "inventory_batches": [ { "id": 827, "lot_number": null, "production_date": null, "expiry_date": "2023-12-30", "name": "Morph II - 827", "tracking_code": "A01234", "stocked_quantities": [ { "warehouse_id": 22, "quantity": 6720 } ] } ] } ] }, "SkuBulkUpsert": { "additionalProperties": true, "description": "The body for creating or updating SKUs in bulk. Properties other than `skus` are ignored.", "properties": { "skus": { "description": "The SKUs to create or update, between 1 and 100.", "items": { "$ref": "#/components/schemas/SkuCreate" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "skus" ], "type": "object", "examples": [ { "skus": [ { "merchant_sku_id": "1A", "name": "Staff of Gandalf", "cost_in_cents": 42000, "weight_in_kg": 2 }, { "merchant_sku_id": "2B", "name": "Millennium Falcon", "batch_tracking_enabled": false } ] } ] }, "SkuCreate": { "additionalProperties": false, "description": "A SKU to create, or to update when the sales channel already has one with the same `merchant_sku_id`.", "properties": { "barcode": { "description": "The SKU's barcode. Must not be an empty string.", "minLength": 1, "type": [ "string", "null" ] }, "batch_tracking_enabled": { "description": "Whether inventory of this SKU is tracked per batch. When left out, a new SKU is not batch-tracked and an existing SKU keeps its setting.", "type": [ "boolean", "null" ] }, "cost_in_cent": { "deprecated": true, "description": "Use `cost_in_cents`, which wins when both are sent. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "cost_in_cents": { "description": "The cost (not the price) of one unit, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "country_code_of_origin": { "description": "The 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code of the country of origin.", "type": [ "string", "null" ] }, "created_at": { "description": "Accepted and ignored; Hive sets the creation time." }, "hs_code": { "description": "The [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System) code.", "type": [ "string", "null" ] }, "id": { "description": "Accepted and ignored; Hive assigns the ID." }, "image_url": { "description": "A publicly accessible URL of an image of the SKU.", "type": [ "string", "null" ] }, "merchant_sku_id": { "description": "Your identifier for the SKU, unique within the sales channel.", "type": "string" }, "name": { "description": "The SKU's name.", "type": "string" }, "weight_in_kg": { "description": "The weight of one unit, in kilograms. A numeric string is accepted too.", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "type": [ "number", "string", "null" ] } }, "required": [ "merchant_sku_id", "name" ], "type": "object", "examples": [ { "merchant_sku_id": "HIVE_TSH_BLK_M", "name": "Hive T-Shirt (Black - M)", "barcode": "2218061549136", "cost_in_cents": 800, "weight_in_kg": 0.3, "batch_tracking_enabled": false } ] }, "SkuInventory": { "additionalProperties": false, "description": "The current inventory of a SKU across all warehouses.", "properties": { "reserved": { "description": "The quantity reserved for orders.", "type": "integer" }, "stocked": { "description": "The quantity available for sale, minus the buffer quantity if one is configured. Can be negative.", "type": "integer" }, "total": { "description": "The quantity available; equal to `stocked` when there is no buffer.", "type": "integer" } }, "readOnly": true, "required": [ "stocked", "reserved", "total" ], "type": "object", "examples": [ { "stocked": 10000, "reserved": 0, "total": 10000 } ] }, "SkuInventoryBatch": { "additionalProperties": false, "description": "The current stock of a SKU in one inventory batch.", "properties": { "expiry_date": { "description": "The batch's expiry date.", "format": "date", "type": [ "string", "null" ] }, "id": { "description": "Hive's unique identifier for the batch.", "format": "int64", "type": "integer" }, "lot_number": { "description": "The batch's lot number.", "type": [ "string", "null" ] }, "name": { "description": "The batch's name.", "type": [ "string", "null" ] }, "production_date": { "description": "The batch's production date.", "format": "date", "type": [ "string", "null" ] }, "stocked_quantities": { "description": "The quantity available for sale in this batch, per warehouse.", "items": { "$ref": "#/components/schemas/SkuInventoryBatchQuantity" }, "type": "array" }, "tracking_code": { "description": "The batch's tracking code.", "type": [ "string", "null" ] } }, "required": [ "id", "lot_number", "production_date", "expiry_date", "name", "tracking_code", "stocked_quantities" ], "type": "object", "examples": [ { "id": 827, "lot_number": null, "production_date": null, "expiry_date": "2023-12-30", "name": "Morph II - 827", "tracking_code": "A01234", "stocked_quantities": [ { "warehouse_id": 22, "quantity": 6720 } ] } ] }, "SkuInventoryBatchQuantity": { "additionalProperties": false, "description": "The quantity of an inventory batch available for sale in one warehouse.", "properties": { "quantity": { "description": "The quantity available for sale.", "type": "integer" }, "warehouse_id": { "description": "Hive's ID of the warehouse.", "format": "int64", "type": "integer" } }, "required": [ "warehouse_id", "quantity" ], "type": "object", "examples": [ { "warehouse_id": 22, "quantity": 6720 } ] }, "SkuInventoryPerWarehouse": { "additionalProperties": false, "description": "The current inventory of a SKU in one warehouse.", "properties": { "reserved": { "description": "The quantity reserved for orders.", "type": "integer" }, "stocked": { "description": "The quantity available for sale, minus the buffer quantity if one is configured. Can be negative.", "type": "integer" }, "total": { "description": "The quantity available; equal to `stocked` when there is no buffer.", "type": "integer" }, "warehouse_id": { "description": "Hive's ID of the warehouse.", "format": "int64", "type": "integer" } }, "required": [ "warehouse_id", "stocked", "reserved", "total" ], "type": "object", "examples": [ { "warehouse_id": 22, "stocked": 6720, "reserved": 0, "total": 6720 } ] }, "SkuUpdate": { "additionalProperties": true, "description": "The body for updating a SKU. Every property is optional; the ones you leave out keep their value. Properties not listed here are ignored.", "properties": { "barcode": { "description": "The SKU's barcode. Must not be an empty string.", "minLength": 1, "type": [ "string", "null" ] }, "batch_tracking_enabled": { "description": "Whether inventory of this SKU is tracked per batch. `null` leaves it unchanged.", "type": [ "boolean", "null" ] }, "cost_in_cent": { "deprecated": true, "description": "Use `cost_in_cents`, which wins when both are sent. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "cost_in_cents": { "description": "The cost (not the price) of one unit, in cents. A string of digits is accepted too.", "pattern": "^-?[0-9]+$", "type": [ "integer", "string", "null" ] }, "country_code_of_origin": { "description": "The 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code of the country of origin.", "type": [ "string", "null" ] }, "hs_code": { "description": "The [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System) code.", "type": [ "string", "null" ] }, "image_url": { "description": "A publicly accessible URL of an image of the SKU.", "type": [ "string", "null" ] }, "merchant_sku_id": { "description": "Your identifier for the SKU, unique within the sales channel.", "type": "string" }, "name": { "description": "The SKU's name.", "type": "string" }, "weight_in_kg": { "description": "The weight of one unit, in kilograms. A numeric string is accepted too.", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "type": [ "number", "string", "null" ] } }, "type": "object", "examples": [ { "name": "Hive T-Shirt (Black - L)", "weight_in_kg": 0.35 } ] }, "Warehouse": { "additionalProperties": false, "description": "A warehouse of the merchant.", "properties": { "city": { "description": "The city the warehouse is in.", "type": [ "string", "null" ] }, "country": { "description": "The 2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code of the country the warehouse is in.", "type": "string" }, "id": { "description": "Hive's unique identifier for the warehouse.", "format": "int64", "type": "integer" }, "name": { "description": "The warehouse's name.", "type": [ "string", "null" ] } }, "required": [ "id", "name", "country", "city" ], "type": "object", "examples": [ { "id": 1, "name": "BER1", "country": "DE", "city": "Berlin" } ] } } } }